---
sidebar_position: 1
---

import {NiivueBrowserWrapper} from '../src/components/NiivueBrowserWrapper';
import { BasicNiivueCanvas } from '../src/components/BasicNiivueCanvas';

# Getting started

NiiVue is an all-in-one package for parsing, loading, and viewing medical imaging data directly in the browser. Its modular design allows you to embed interactive visualizations into your pages using any framework—such as Angular, Vue, or React—or even as pure HTML. Below is an example of NiiVue embedded in a Docusaurus MDX page using a custom React component:

<NiivueBrowserWrapper>
  <BasicNiivueCanvas
  images={[
    { url: "https://niivue.github.io/niivue-demo-images/mni152.nii.gz" }
  ]}
  />
</NiivueBrowserWrapper>


## Installation

To install NiiVue, you can use your favorite package manager (npm, pnpm, yarn, etc.):

```bash
npm install @niivue/niivue
```

## Usage

### Basic - No framework

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>NiiVue</title>
  </head>
  <body>
    <canvas id="gl" width="640" height="640"></canvas>
  </body>
  <script type="module" async>
    import { Niivue } from "https://unpkg.com/@niivue/niivue@0.57.0/dist/index.js"
    var volumeList = [
      { url: "https://niivue.github.io/niivue-demo-images/mni152.nii.gz" },
    ];
    var nv = new Niivue({ isResizeCanvas: false });
    await nv.attachTo("gl");
    await nv.loadVolumes(volumeList);
  </script>
</html>
```

### React

```jsx
import { useRef, useEffect } from "react";
import { Niivue } from "@niivue/niivue";

const NiiVue = ({ imageUrl }) => {
  const canvas = useRef();
  const nvRef = useRef();
  useEffect(() => {
    const volumeList = [
      {
        url: imageUrl,
      },
    ];
    async function setupAndLoad() {
      const nv = new Niivue();
      nv.attachToCanvas(canvas.current);
      await nv.loadVolumes(volumeList);
      const nvRef.current = nv
    }
    setupAndLoad()
  }, [imageUrl]);

  return <canvas ref={canvas} height={480} width={640} />;
};

// use as: <NiiVue imageUrl={someUrl}> </NiiVue>
```

### Vue

```jsx
<script>
import {Niivue} from '@niivue/niivue'
const nv = new Niivue()


export default {
  name: 'App',
  props: {

  },
  data(){
    return {
      volumeList: [
        {
          url: "./mni152.nii.gz",
        }
      ]

    }
  },

  mounted() {
    nv.attachTo('gl')
    await nv.loadVolumes(this.volumeList)
  }
}

</script>

<template>
<canvas id="gl" height="480" width="640">
</canvas>
</template>
```

### Angular

```javascript
import { Component, OnInit, ViewChild } from "@angular/core";

import { Niivue } from "@niivue/niivue";

@Component({
  selector: "app-niivue-view",
  templateUrl: "./niivue-view.component.html",
  styleUrls: ["./niivue-view.component.sass"],
})
export class NiivueViewComponent implements OnInit {
  @ViewChild("gl") canvas: HTMLCanvasElement | undefined;

  constructor() {}

  ngOnInit(): void {
    const url = "/assets/mni152.nii.gz";
    const volumeList = [
      {
        url,
      },
    ];
    const niivue = new Niivue();
    niivue.attachTo("gl");
    await niivue.loadVolumes(volumeList);
  }
}
```

## Limitations

NiiVue is a graphical visualization tool and therefore cannot be used as a command-line utility in Node.js environments. It is designed to be embedded in a web browser window. However, as demonstrated in the end-to-end regression tests, NiiVue can run headlessly using Playwright to render a WebGL canvas and save a screenshot to disk.

